\chapter{Metering}

The system named \texttt{cleavir-meter} defines a package with the
same name, and functionality for \emph{metering}. 

Metering is an idea inspired by the \multics{} operating system, and
consists of accumulating performance information whenever doing so
does not noticeably degrade performance of the subsystem being
metered.  The performance information consists at the very least of
counting the number of invocations of a function and the processor
time the invocations took to execute.

\Defclass {meter}

This class is the base class for all meters.

\Defclass {basic-meter}

This class is a subclass of the class \texttt{meter}.  Meters of this
type collect information about processor time and number of
invocations in a way that make it possible to determine minimum and
maximum processor time for the invocations as well as the standard
deviation for the processor time.

\Defclass {size-meter}

This class is a subclass of the class \texttt{basic-meter}.  In
addition to counting the number of invocations and measuring processor
time, this class allows client code to associate a \emph{size} with
each invocation.

\Defgeneric {reset} {meter}

This generic function uses the \texttt{progn} method combination.  It
resets all information to its initial value.

\Defun {report} {meter \optional{} stream}

This function generates a report on \texttt{stream}.
The \texttt{stream} argument defaults to the value of the special
variable \texttt{*standard-output*}.

\Defmacro {with-meter} {(meter-variable meter-form) \body{} body}

This macro evaluates \textit{body} in a context where
\textit{meter-variable} is bound to the value of the form
\textit{meter-form}.  Some simple processing is done automatically,
such as noting the processor time before and after the evaluation of
the forms in \textit{body}.  More complex processing can be done by
some form in \textit{body} by referring to \textit{meter-variable}.

This macro accomplishes its task by wrapping the forms in
\textit{body} in a \emph{thunk} and calling the generic function
\texttt{invoke-with-meter} with \textit{meter-variable} and the thunk
as arguments.

\Defgeneric {invoke-with-meter} {meter function}

This generic function is called from the expansion of the macro
\texttt{with-meter} with the meter variable and  \emph{thunk}
containing the body of the macro call.
